---
title: Configuration Files
description: "Understanding and managing VibeKit CLI configuration files"
---

## Overview

VibeKit CLI stores configuration and data in the `~/.vibekit/` directory. These files control sandbox behavior, redaction settings, analytics, and logging preferences.

## File Locations

### User Configuration Directory

All VibeKit CLI files are stored in `~/.vibekit/`:

| File | Location | Purpose |
|------|----------|---------|
| `settings.json` | `~/.vibekit/settings.json` | User preferences and feature toggles |
| `logs/` | `~/.vibekit/logs/` | Agent interaction logs by date |
| `analytics/` | `~/.vibekit/analytics/` | Usage statistics and performance data |

### Project Files

| File | Location | Purpose |
|------|----------|---------|
| `.env` | Project root | Environment variables (API keys) |

## Settings Configuration

### ~/.vibekit/settings.json

Controls VibeKit CLI behavior and features:

```json
{
  "sandbox": {
    "enabled": false
  },
  "redaction": {
    "enabled": true
  },
  "analytics": {
    "enabled": true
  },
  "aliases": {
    "enabled": false
  }
}
```

### Settings Options

#### Sandbox Settings

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `sandbox.enabled` | `boolean` | `false` | Enable Docker sandbox by default |

When enabled, agents run in Docker containers instead of directly on your system.

#### Redaction Settings

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `redaction.enabled` | `boolean` | `true` | Enable automatic PII redaction from outputs |

The redaction system automatically removes sensitive information from agent outputs.

#### Analytics Settings

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `analytics.enabled` | `boolean` | `true` | Track usage statistics and performance |

Analytics track session duration, success rates, and error patterns.

#### Aliases Settings

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `aliases.enabled` | `boolean` | `false` | Enable global command aliases |

When enabled, you can use `claude` instead of `vibekit claude`.

## Managing Settings

### Interactive Settings

Use the interactive settings interface:

```bash
vibekit
```

This provides a TUI for toggling options:
- Navigate with arrow keys
- Toggle with space bar
- Save with enter

### Manual Editing

Edit settings directly:

```bash
# Open in editor
vi ~/.vibekit/settings.json

# Validate JSON
cat ~/.vibekit/settings.json | jq '.'
```

## Environment Variables

### API Keys

Set API keys for your agents:

```bash
# Claude Code CLI
export ANTHROPIC_API_KEY="sk-ant-..."

# Gemini CLI (when available)
export GOOGLE_API_KEY="..."

# Add to shell profile for persistence
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc
```

### Network Configuration

Configure network settings:

```bash
# Use external proxy if needed
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

# Enable debug logging
export VIBEKIT_DEBUG="1"
```

### Project-Level Environment

Create `.env` file in your project:

```bash
# .env
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# Custom environment variables for your project
DATABASE_URL=postgresql://...
API_BASE_URL=https://api.example.com
```

## Data Storage

### Log Files

Logs are organized by date in `~/.vibekit/logs/`:

```
~/.vibekit/logs/
├── 2024-01-15/
│   ├── claude-10-30-00.log
│   ├── claude-14-45-12.log
│   └── gemini-16-20-35.log
├── 2024-01-16/
│   └── claude-09-15-42.log
```

Each log file contains:
- Agent commands and arguments
- Execution output and errors
- Performance timings
- File changes made

### Analytics Data

Analytics are stored in `~/.vibekit/analytics/`:

```
~/.vibekit/analytics/
├── sessions/
│   ├── claude-2024-01-15.json
│   └── gemini-2024-01-15.json
└── summary.json
```

Data includes:
- Session duration and outcome
- Commands executed
- Files modified
- Error messages and warnings

## Global Aliases

### Setting Up Aliases

Enable global aliases to use `claude` directly:

```bash
# Enable in settings
vibekit  # Toggle aliases to enabled

# Install aliases to shell
vibekit setup-aliases

# Restart terminal or reload shell
source ~/.zshrc
```

### Using Aliases

After setup, use commands directly:

```bash
# Instead of: vibekit claude "Generate code"
claude "Generate code"

# Instead of: vibekit gemini "Ask question"
gemini "Ask question"
```

### Diagnosing Alias Issues

Check alias setup:

```bash
vibekit diagnose-aliases
```

This shows:
- Settings status
- VibeKit command availability
- Shell alias functionality
- Current active aliases

## Configuration Precedence

Settings are applied in this order (later overrides earlier):

1. Built-in defaults
2. Settings file (`~/.vibekit/settings.json`)
3. Environment variables
4. Command line options

Example:
```bash
# Settings: sandbox.enabled = false
# Environment: (none)
# Command line wins:
vibekit claude --sandbox docker "Generate code"
```

## Backup and Restore

### Manual Backup

Create backup of all VibeKit data:

```bash
# Create timestamped backup
BACKUP_DIR="$HOME/vibekit-backup-$(date +%Y%m%d-%H%M%S)"
cp -r ~/.vibekit "$BACKUP_DIR"
tar -czf "$BACKUP_DIR.tar.gz" -C "$HOME" "$(basename "$BACKUP_DIR")"
rm -rf "$BACKUP_DIR"

echo "Backup created: $BACKUP_DIR.tar.gz"
```

### Restore Configuration

```bash
# Restore from backup
tar -xzf ~/vibekit-backup-20240115-103000.tar.gz -C ~/
mv ~/vibekit-backup-20240115-103000 ~/.vibekit
```

## Maintenance

### Clean Data

Remove old logs and analytics:

```bash
# Clean all data
vibekit clean

# Clean specific data types
vibekit clean --logs      # Remove log files
vibekit clean --analytics # Remove analytics data
vibekit clean --docker   # Remove Docker resources
```

### Reset Configuration

Reset settings to defaults:

```bash
# Remove settings file (will recreate with defaults)
rm ~/.vibekit/settings.json

# Or reset all data (careful!)
rm -rf ~/.vibekit
```

## Troubleshooting

### Corrupted Settings

Check settings file validity:

```bash
# Validate JSON
jq '.' ~/.vibekit/settings.json

# Fix corrupted file
echo '{}' > ~/.vibekit/settings.json
```

### Permission Issues

Fix file permissions:

```bash
# Ensure proper ownership and permissions
chmod 700 ~/.vibekit
find ~/.vibekit -type f -exec chmod 600 {} \;

# Check current permissions
ls -la ~/.vibekit/
```

### Missing Dependencies

Check for required tools:

```bash
# Check for Claude Code CLI
claude --version

# Check for Docker (if using sandbox)
docker --version

# Diagnose common issues
vibekit diagnose-aliases
```

## Best Practices

### 1. Secure API Keys

Never commit API keys to version control:

```bash
# .gitignore
.env
*.log
```

Use environment variables or secure storage.

### 2. Regular Cleanup

Set up automatic cleanup:

```bash
# Add to crontab for weekly cleanup
0 0 * * 0 vibekit clean --logs
```

### 3. Monitor Usage

Use analytics to understand your usage patterns:

```bash
# Weekly usage review
vibekit analytics --days 7 --summary

# Export for analysis
vibekit analytics --export weekly-report.json --days 7
```

### 4. Safe Experimentation

Enable Docker sandbox for unknown or experimental prompts:

```bash
# Enable sandbox in settings for safety
vibekit

# Or use per-command
vibekit claude --sandbox docker "Experimental code generation"
```

## Related Topics

- [Environment Variables](/cli/environment-variables) - Runtime configuration
- [Installation](/cli/installation) - Initial setup
- [Quick Reference](/cli/quick-reference) - Common commands